home *** CD-ROM | disk | FTP | other *** search
/ MacWorld 1999 August / Macworld (1999-08).dmg / Shareware World / Info / For Developers / MADE 1.4.0 / Essentials / Essential Extras.h < prev    next >
Text File  |  1999-05-26  |  16KB  |  340 lines
  1. /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
  2. /*                                                                   */
  3. /*        MADE - Macintosh Application Development Essentials        */
  4. /*        ---------------------------------------------------        */
  5. /*           (c) Sig Software, http://www.sigsoftware.com/           */
  6. /*                                                                   */
  7. /* These files can only be used for experimental purposes. To obtain */
  8. /* fully commented code, source code for the functions in Essential  */
  9. /*   Extras.h and permission for usage in final projects, you must   */
  10. /*    purchase a license. See documentation for more information.    */
  11. /*                                                                   */
  12. /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
  13. /*                                                                   */
  14. /*  Essential Extras.h                                               */
  15. /*  ------------------                                               */
  16. /*                                                                   */
  17. /*  Headers for extra utility functions which you will receive when  */
  18. /*  you purchase a license for MADE. Included in unregistered        */
  19. /*  version so you know what you're missing!                         */
  20. /*                                                                   */
  21. /*  Version 1.2.0 - 20th November 1998                               */
  22. /*  Version 1.4.0 - 26th May 1999 - Added threading, navigation      */
  23. /*                                                                   */
  24. /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
  25.  
  26. #include "User Extra Settings.h"
  27.  
  28. /*
  29.     Essential Dialogs.c
  30.     
  31.     These functions are shortcuts for common operations you need to perform on
  32.     modal or modeless dialog boxes.
  33. */
  34.  
  35. /*
  36.         For use with any dialog items
  37. */
  38.  
  39. Handle            GetItemHandle(DialogPtr dialog, short item);
  40. void            GetItemRect(DialogPtr dialog, short item, Rect* rect);
  41. void            SetItemHandle(DialogPtr dialog, short item, Handle handle);
  42. void            InvalItem(DialogPtr dialog, short item);
  43.                     // invalidates an item, causing it to be redrawn in next event loop
  44. /*
  45.         For use with check boxes, radio buttons, push buttons and other controls
  46. */
  47.  
  48. short            GetItemValue(DialogPtr dialog, short item);
  49. void            SetItemValue(DialogPtr dialog, short item, short value);
  50. Boolean            ToggleItem(DialogPtr dialog, short item);
  51.                     // toggles an item (on<->off) and returns its new value
  52. void            SetItemEnabled(DialogPtr dialog, short item, Boolean enabled);
  53.                     // uses HiliteControl(..., 255);
  54.                     
  55. /*
  56.         For use with static text and edit text items
  57. */
  58.  
  59. void            GetItemText(DialogPtr dialog, short item, Str255 string);
  60. long            GetItemNumber(DialogPtr dialog, short item);
  61. void            SetItemText(DialogPtr dialog, short item, Str255 string);
  62. void            SetItemNumber(DialogPtr dialog, short item, long number);
  63.  
  64. /*
  65.     Essential Strings.c
  66.     
  67.     These optimised functions perform many manipulations on MacOS Str255 structures.
  68.     Where there is a pair ...String and ...Chars, use the ...String version when dealing
  69.     with two Str255s, and the ...Chars version when dealing with one Str255 and one
  70.     string specified by a pointer and length. Read the variable names carefully to
  71.     determine which order to pass in the parameters!
  72. */
  73.  
  74. /*
  75.         Copying strings
  76. */
  77.  
  78. void            CloneString(Str255 source, Str255 result);
  79. void            CloneChars(unsigned char* sourcePtr, unsigned char sourceLen, Str255 result);
  80.  
  81. /*
  82.         Adding and removing from strings
  83.         
  84.         A position of zero specifies the beginning of the string.
  85. */
  86.  
  87. void            AppendString(Str255 original, Str255 append);
  88. void            AppendChars(Str255 original, unsigned char* appendPtr, unsigned char appendLen);
  89. void            InsertString(Str255 insert, Str255 original, unsigned char position);
  90. void            InsertChars(unsigned char* insertPtr, unsigned char insertLen,
  91.                             Str255 original, unsigned char position);
  92. void            RemoveFromString(Str255 original, unsigned char position, unsigned char count);
  93.  
  94. /*
  95.         Searching and comparing strings
  96.         
  97.         The string tables which are used when searching case INsensitively are for Roman
  98.         scripts only. Use the MacOS international functions if you want to be script-
  99.         independent, but these will be quicker otherwise.
  100.         
  101.         A position of zero returned by a Find function means the string was not found. A
  102.         position of one means it was found at the start, two for the second characters, etc...
  103.         
  104.         The Relative functions return a value of -1, 0, 1 for first-second, i.e. :
  105.         -1 => the first string is alphabetically before the second
  106.          0 => the first string is alphabetically identical to the second
  107.          1 => the first string is alphabetically after the second
  108. */
  109.  
  110. unsigned char    FindInString(Str255 find, Str255 within, Boolean caseSensitive);
  111. unsigned char    FindChars(unsigned char* findPtr, unsigned char findLen,
  112.                           unsigned char* inPtr, unsigned char inLen, Boolean caseSensitive);
  113. short            RelativeString(Str255 first, Str255 second, Boolean caseSensitive);
  114. short            RelativeChars(unsigned char* firstPtr, unsigned char firstLen,
  115.                               unsigned char* secondPtr, unsigned char secondLen,
  116.                               Boolean caseSensitive);
  117.  
  118. /*
  119.     Essential Buffers.c
  120.     
  121.     These functions let you deal with buffers, for access to files and memory. Their major
  122.     benefit is that they do things in lumps so that your code runs quickly, and is not bogged
  123.     down too much by the vagaries of Apple's memory and file manager.
  124. */
  125.  
  126. #define    memoryBufferBlockSize    1024
  127. #define    saveBufferBlockSize        1024
  128. #define    loadBufferBlockSize        1024
  129.             // set these to the size you want. Bigger means slightly faster but
  130.             // uses more memory. 1024 (i.e. 1K) should be perfectly adequate.
  131.  
  132. /*
  133.         Memory Buffer - automatically growing block of memory
  134.         
  135.         Open with CreateMemoryBuffer, then write as much as you want using WriteMemoryBuffer,
  136.         checking for returned errors as you go. When you're finished, call CloseMemoryBuffer.
  137.         The handle it returns will be unlocked and is now owned by you. You must dispose of
  138.         it yourself using DestroyHandle once you're finished with it.
  139. */
  140.     
  141. typedef struct MemoryBuffer {
  142.     Handle        handle;
  143.     long        allocated, used;
  144. } MemoryBuffer;
  145.  
  146. Error            CreateMemoryBuffer(MemoryBuffer* buffer);
  147. Error            WriteMemoryBuffer(MemoryBuffer* buffer, void* dataPtr, long count);
  148. Handle            CloseMemoryBuffer(MemoryBuffer* buffer);
  149.  
  150. /*
  151.         Save Buffer - buffered access for writing a file
  152.         
  153.         Open with OpenSaveBuffer, then write as much as you want using WriteSaveBuffer,
  154.         checking for returned errors as you go. When you're finished, call CloseSaveBuffer.
  155.         OpenSaveBuffer will delete any previously existing file with the specified
  156.         location, so be warned. If you used the Standard File dialogs to select the file,
  157.         the user will already have been asked about replacing the previous file.
  158. */
  159.     
  160. typedef struct SaveBuffer {
  161.     char        data[saveBufferBlockSize];
  162.     short        fileRefNum;
  163.     long        used;
  164. } SaveBuffer;
  165.  
  166. Error            OpenSaveBuffer(SaveBuffer* buffer, FSSpec* fileSpec, OSType creator, OSType type);
  167. Error            WriteSaveBuffer(SaveBuffer* buffer, void* dataPtr, long count);
  168. Error            CloseSaveBuffer(SaveBuffer* buffer);
  169.  
  170. /*
  171.         Load Buffer - buffered access for reading a file
  172.         
  173.         Open with OpenLoadBuffer, then read using ReadLoadBuffer or ReadLoadBufferUntil,
  174.         checking for returned errors as you go. LoadBufferRemaining will tell you how
  175.         much of the file remains for reading. When you're finished, call CloseLoadBuffer.
  176. */
  177.     
  178. typedef struct LoadBuffer {
  179.     char        data[loadBufferBlockSize];
  180.     short        fileRefNum;
  181.     long        read, valid;
  182. } LoadBuffer;
  183.  
  184. Error            OpenLoadBuffer(LoadBuffer* buffer, FSSpec* fileSpec);
  185. Error            ReadLoadBuffer(LoadBuffer* buffer, void* dataPtr, long count);
  186. Error            ReadLoadBufferUntil(LoadBuffer* buffer, char untilChar,
  187.                                     char* dataPtr, long* count);
  188.                     // untilChar will be matched exactly. The data returned will include
  189.                     // this character. On entry, the variable pointed to be count must
  190.                     // contain the maximum number of characters to read. On exit, it will
  191.                     // tell you the actual number of characters read. You can check
  192.                     // whether you had enough space to find the last character by looking
  193.                     // at the last character, i.e. dataPtr[*count-1].
  194. Error            LoadBufferRemaining(LoadBuffer* buffer, long* remaining);
  195. void            CloseLoadBuffer(LoadBuffer* buffer);
  196.  
  197. /*
  198.     Essential URLs.c
  199.     
  200.     These functions let you open a URL in the user's browser, using Internet Config
  201.     first (if Use_Internet_Config is set to 1), then trying Netscape then Internet
  202.     Explorer. The other functions are used along the way, and are put here because
  203.     you might want to put them to other purposes.
  204. */
  205.  
  206. Error            OpenURL(Str255 url);
  207. Error            FindApplication(OSType creator, ProcessSerialNumber *process);
  208.                     // High-level function. This tries FindApplicationProcess first,
  209.                     // then FindApplicationFile and OpenApplicationFile.
  210. Error            FindApplicationProcess(OSType creator, ProcessSerialNumber *process);
  211.                     // Looks for the process currently running
  212. Error            FindApplicationFile(OSType creator, FSSpec* fileSpec);
  213.                     // Looks for the process in desktop files of all mounted volumes
  214. Error            OpenApplicationFile(FSSpec* fileSpec, ProcessSerialNumber *process);
  215.                     // Launches application
  216. Error            SendGetURLEvent(ProcessSerialNumber *process, Str255 url);
  217.                     // Sends the standard GURL event to the specified process
  218.                     
  219. /*
  220.     Essential Threads.c
  221.     
  222.     These functions implement a simple, non-preemptive, non-prioritizing threading
  223.     architecture which doesn't require Apple's Threads Manager.
  224. */
  225.  
  226. typedef enum { threadInit, threadWork, threadPaused, threadResumed, threadKill } ThreadMessage;
  227.     // Commands sent to your thread procedure
  228.     // On threadInit, do whatever is necessary to start off but don't start working
  229.     // On threadWork, do your thread's actual work - make it as little as possible
  230.     // On threadPaused, you have just gone from being unpaused to paused
  231.     // On threadResumed, you have just gone from being paused to bring unpaused
  232.     // On threadKill, clear up any extra data you allocated. You will received threadKill
  233.     // either if your thread was killed from outside or if you returned threadDone below
  234.  
  235. typedef enum { threadOK, threadError, threadPause, threadDone } ThreadResult;
  236.     // Your thread procedure must return one of these after every call
  237.     // Return threadOK if things are OK but there's still more work to be done
  238.     // Return threadError if you want to be stop without a threadKill message
  239.     // Return threadPause to pause your thread until ThreadResume() is called for it
  240.     // Return threadDone if there's nothing left to do
  241.  
  242. typedef ThreadResult (ThreadProc) (ThreadMessage command, void* threadData, long dataSize);
  243.     // This is a type definition for your thread procedure, make something like:
  244.     // ThreadResult MyThread(ThreadCommand command, void* threadData, long dataSize);
  245.     // Command is what to do, (threadData, dataSize) are the data input for your thread
  246.  
  247. typedef struct Thread Thread;
  248.  
  249. Thread*        ThreadAdd(Error* error, ThreadProc threadProc, void* threadData, long dataSize);
  250.                 // Create a new thread, returns thread or 0 if fail. Data copied into thread
  251. void        ThreadKill(Thread* thread);
  252.                 // Kill the thread immediately (sends threadKill then disposes)
  253. void        ThreadPause(Thread* thread);
  254.                 // Pauses the thread immediately
  255. void        ThreadResume(Thread* thread);
  256.                 // Resumes the thread immediately
  257. Boolean        ThreadsBusy();
  258.                 // Returns true if we have thread work to do, i.e. want to hog the CPU
  259. void        ThreadsWork(long workTicks);
  260.                 // Sets threads to work for workTicks 60ths of a second - since this is
  261.                 // non-preemptive, it relies on the good will of threadProc!
  262.     
  263. /*
  264.     Essential Navigation.c
  265.     
  266.     These functions implement open and save file dialog boxes which automatically
  267.     use Navigation Services if available (beginning Mac OS 8.5). To use these functions,
  268.     you need to do 3 further things :
  269.     
  270.     1. Add the NavigationLib library to your project (in :Libraries:MacOS Common). In
  271.        order to work with pre-8.5 systems, make sure you select the 'Import Weak' option.
  272.     2. Create a 'kind' resource with kind strings for formats you can open
  273.        (see Inside Macintosh: More Macintosh Toolbox). This is easiest with Rez.
  274.     3. Ensure that your drag-and-drop tracking and receiving code can cope with the fact
  275.        that it may get messages for Navigation Services windows (silly if you ask me).
  276. */
  277.  
  278. typedef struct {
  279.     FSSpec                    fileSpec; // the full file
  280.     Boolean                    folder, visible; // Boolean flags if a folder, if visible
  281.     unsigned long            created, modified; // Mac OS date/time structures
  282.  
  283.     union {    
  284.         struct {
  285.             Boolean            locked; // Boolean flag if file is locked
  286.             Boolean            dataOpen, resOpen; // Boolean flags if data or resource fork open
  287.             unsigned long    dataSize, resourceSize; // The logical size of these forks
  288.             FInfo            finderInfo; // Finder info structure (contains type, creator)
  289.             FXInfo            moreFinderInfo; // Additional Finder info
  290.         }                    
  291.                             file; // Access this structure with .more.file
  292.         struct {
  293.             unsigned long    numberFiles; // Number of files in folder
  294.             DInfo            finderInfo; // Finder info structure
  295.             DXInfo            moreFinderInfo; // Additional Finder info
  296.         }
  297.                             folder; // Access this structure with .more.folder
  298.     }
  299.                             more;
  300. } MADENavigationItemInfo;
  301.     // This structure is passed to your filter procedure to give it the necessary
  302.     // information about the file it is filtering
  303.  
  304. typedef Boolean (MADENavigationItemFilter) (MADENavigationItemInfo* item);
  305.     // This is a type definition for your navigation item filtering procedure
  306.     // You want something like: Boolean MyFilter(MADENavigationItemInfo* item);
  307.     // You should return true from this to _display_ the item (unlike StandardFile API)
  308.  
  309. Boolean MADENavigationGetFile(OSType appCreator, short numberTypes, OSType types[],
  310.         MADENavigationItemFilter* filter, FSSpec* resultFile, Boolean *stationery);
  311.     // Does a get file (i.e. open dialog box) with or without Navigation Services
  312.     // appCreator is your application's signature, numTypes is the number of types in types
  313.     // (maximum is 4), -1 to pass all and use filter,
  314.     // filter is an additional filtering procedure for items (0 for none),
  315.     // resultFile will have the file to open, *stationery will be true if the file to open
  316.     // is stationery (pass 0 if you don'y care). Returns true if user indicated to go ahead
  317.     
  318. Boolean MADENavigationChooseFile(OSType appCreator, short numberTypes, OSType types[],
  319.         MADENavigationItemFilter* filter, FSSpec* resultFile, Boolean *stationery);
  320.     // Save as MADENavigationGetFile but uses Navigation Services' Choose interface
  321.     // instead of Open interface. Also doesn't go through translation.
  322.     
  323. Boolean MADENavigationChooseFolder(OSType appCreator, MADENavigationItemFilter* filter,
  324.     FSSpec* resultFile);
  325.     // Save as MADENavigationChooseFile but allows selection of a folder, either using
  326.     // a customised Standard File dialog or Navigation Services.
  327.     
  328. Boolean MADENavigationChooseFileOrFolder(OSType appCreator, MADENavigationItemFilter* filter,
  329.     FSSpec* resultFile, Boolean *stationery);
  330.     // Save as MADENavigationChooseFolder but allows selection of files _or_ a folder,
  331.     // either using a customised Standard File dialog or Navigation Services.
  332.     
  333. Boolean MADENavigationPutFile(Str255 prompt, OSType appCreator, OSType type,
  334.         Str255 defaultName, FSSpec* resultFile, Boolean* replacing);
  335.     // Does a put file (i.e. save as dialog box) with or without Navigation Services
  336.     // prompt is the text prompt (0 for none), appCreator is your application's signature,
  337.     // type is the type of file you will save, resultFile will have the file to save as,
  338.     // defaultName is the default file name (0 for default), *replacing will be true if the
  339.     // user is replacing a previous file. Returns true if user indicated to go ahead
  340.